home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 23 / AACD 23.iso / AACD / Programming / tek / doc / teklib.doc next >
Text File  |  2001-05-16  |  77KB  |  2,734 lines
  1. TABLE OF CONTENTS
  2.  
  3. teklib/TCreateTask
  4. teklib/TAllocSignal
  5. teklib/TFreeSignal
  6. teklib/TSignal
  7. teklib/TSetSignal
  8. teklib/TWait
  9. teklib/TTimedWait
  10. teklib/TInitLock
  11. teklib/TLock
  12. teklib/TUnlock
  13. teklib/TCreatePort
  14. teklib/TWaitPort
  15. teklib/TTimeDelay
  16. teklib/TTimeQuery
  17. teklib/TTimeReset
  18. teklib/TGetRandomSeed
  19. teklib/TTaskAlloc
  20. teklib/TTaskAlloc0
  21. teklib/TTaskFree
  22. teklib/TTaskRealloc
  23. teklib/TTaskGetSize
  24. teklib/TTaskAllocMsg
  25. teklib/TTaskBaseTask
  26. teklib/TTaskHeapMMU
  27. teklib/TTaskMsgMMU
  28. teklib/TTaskGetData
  29. teklib/TTaskSetData
  30. teklib/TTaskPort
  31. teklib/TFreeMsg
  32. teklib/TPutMsg
  33. teklib/TPutReplyMsg
  34. teklib/TGetMsg
  35. teklib/TAckMsg
  36. teklib/TReplyMsg
  37. teklib/TDropMsg
  38. teklib/TSendMsg
  39. teklib/TGetMsgAttrs
  40. teklib/TGetMsgStatus
  41. teklib/TGetMsgSize
  42. teklib/TAddHead
  43. teklib/TAddTail
  44. teklib/TRemove
  45. teklib/TInsert
  46. teklib/TRemHead
  47. teklib/TRemTail
  48. teklib/TSeekNode
  49. teklib/TInitList
  50. teklib/TListEmpty
  51. teklib/TFirstNode
  52. teklib/TLastNode
  53. teklib/TGetTagValue
  54. teklib/TGetTagArray
  55. teklib/TInitTags
  56. teklib/TAddTag
  57. teklib/TGetRandom
  58. teklib/TMemCopy
  59. teklib/TMemCopy32
  60. teklib/TMemFill
  61. teklib/TMemFill32
  62. teklib/TInitMemHead
  63. teklib/TStaticAlloc
  64. teklib/TStaticFree
  65. teklib/TStaticRealloc
  66. teklib/TStaticGetSize
  67. teklib/TCreatePool
  68. teklib/TPoolAlloc
  69. teklib/TPoolRealloc
  70. teklib/TPoolFree
  71. teklib/TPoolGetSize
  72. teklib/TInitMMU
  73. teklib/TMMUAlloc
  74. teklib/TMMUFree
  75. teklib/TMMURealloc
  76. teklib/TMMUAlloc0
  77. teklib/TMMUGetSize
  78. teklib/TMMUAllocHandle
  79. teklib/TMMUAllocHandle0
  80. teklib/TMMUFreeHandle
  81. teklib/TDestroy
  82. teklib/TAddSockPort
  83. teklib/TRemSockPort
  84. teklib/TFindSockPort
  85. teklib/TCreateTask
  86.  
  87.     NAME
  88.         TCreateTask - create task.
  89.  
  90.     SYNOPSIS 
  91.         task = TCreateTask(parenttask, function,  taglist);
  92.         TAPTR              TAPTR       TTASKFUNC* TTAGITEM* 
  93.     
  94.     FUNCTION
  95.         launch a task at the given function, or create an
  96.         application's basetask.
  97.         
  98.         for creating a basetask, both parenttask and function must
  99.         be TNULL. all further tasks and most TEKlib internal
  100.         structures will be derived from a basetask in the end, so
  101.         it's usually one of the first objects created in a TEKlib
  102.         framework.
  103.         
  104.         for creating a child task, parenttask must refer to the
  105.         caller's context, and function usually refers to a task
  106.         entry function. sometimes it may be desirable to only call
  107.         an init function in a new context, so function may be TNULL,
  108.         provided that the tag argument TTask_InitFunc is specified.
  109.         if neither a task entry function nor an init function is
  110.         specified, TCreateTask() returns TNULL.
  111.         
  112.     INPUTS
  113.         parenttask - parent task. for creating a child task, this must
  114.                      refer to the current context. TNULL for creating
  115.                      an application's base task.
  116.                      
  117.         function   - function entry. this must refer to a function
  118.                      with the prototype TVOID (*function)(TAPTR task),
  119.                      or may optionally be TNULL when the tag
  120.                      TTask_InitFunc is specified in the taglist
  121.                      arguments. TNULL when a basetask is to be created.
  122.         
  123.         taglist    - pointer to an array of tag items.
  124.         
  125.     TAGS
  126.         TTask_UserData, TAPTR
  127.             pointer to arbitrary user data. a task's userdata field
  128.             can be obtained with TTaskGetData().
  129.             default: TNULL
  130.         
  131.         TTask_InitFunc, TBOOL (*function)(TAPTR task)
  132.             pointer to a user init function. TCreateTask() will initially
  133.             call this function inside a newly created context, and enter
  134.             the task's main function entry only if the init function
  135.             returns TTRUE. otherwise child task creation is entirely
  136.             abandoned, the task entry function is never called, and
  137.             TCreateTask() returns TNULL. when this argument is specified,
  138.             the task's function entry argument may be TNULL.
  139.             default: TNULL
  140.  
  141.         TTask_CreatePort, TBOOL
  142.             create an initial message-port in the child's context.
  143.             TCreateTask() will entirely fail and return TNULL when
  144.             a childport was requested and could not be established.
  145.             by default, any newly created task will be supplied with
  146.             a messageport. default: TTRUE
  147.         
  148.         TTask_MMU, TAPTR
  149.             pointer to a memory management unit for allocating the task's
  150.             structures. default: the heap MMU of an application's
  151.             basetask, or TNULL if this is the basetask to be created.
  152.         
  153.         TTask_HeapMMU, TAPTR
  154.             pointer to a memory management unit. the new task's heap
  155.             memory manager will be put on top of this MMU.
  156.             default: the argument or default value to TTask_MMU
  157.  
  158.     RESULTS
  159.         task       - task handle, or TNULL if the task could not be
  160.                      established. a task handle is destroyed with a
  161.                      call to TDestroy().
  162.  
  163.     SEE ALSO
  164.         TDestroy(), TTaskGetData(), TTaskSetData(), TTaskPort(),
  165.         TTaskBaseTask(), TCreatePort(), TTaskHeapMMU()
  166.  
  167.  
  168. teklib/TAllocSignal
  169.  
  170.     NAME
  171.         TAllocSignal - allocate a single or a set of signals
  172.  
  173.     SYNOPSIS
  174.         signals = TAllocSignal(task, prefsignals)
  175.         TUINT                  TAPTR TUINT
  176.  
  177.     FUNCTION
  178.         allocate a signal (or a set of preferred signals) from the
  179.         given task. if prefsignals is 0, then this function will try to
  180.         reserve any single free signal. if prefsignals is not 0, this
  181.         function tries to reserve the exact set specified, and returns
  182.         0 if any of the specified signals are already in use.
  183.  
  184.     INPUTS
  185.         task        - task to which the signal (or signal set) will belong
  186.         prefsignals - preferred signals to allocate, or zero
  187.  
  188.     RESULTS
  189.         signals     - allocated signal mask. zero if out of signals, or
  190.                       when any of prefsignals are already in use.
  191.  
  192.     NOTES
  193.         signals no longer needed should be freed with TFreeSignal().
  194.         
  195.     SEE ALSO
  196.         TFreeSignal(), TSignal(), TSetSignal(), TWait()
  197.  
  198.  
  199. teklib/TFreeSignal
  200.  
  201.     NAME
  202.         TTaskFreeSignal - free a single or set of task signals
  203.  
  204.     SYNOPSIS
  205.         TFreeSignal(task, sigmask)
  206.                     TAPTR TUINT
  207.  
  208.     FUNCTION
  209.         free a single or set of signals and return it to a task's
  210.         pool of allocatable signals.
  211.  
  212.     INPUTS
  213.         task    - task to which the signal(s) belong.
  214.         sigmask - signal mask to be freed. it is safe to pass
  215.                   0 (no-signal) here.
  216.  
  217.     SEE ALSO
  218.         TAllocSignal()
  219.  
  220.  
  221. teklib/TSignal
  222.  
  223.     NAME
  224.         TSignal - submit a set of signals to a task.
  225.  
  226.     SYNOPSIS 
  227.         TSignal(task, signals);
  228.                 TAPTR TUINT
  229.         
  230.     FUNCTION
  231.         submit signals to a task. when the task was waiting
  232.         for the specified signals, it will resume operation.
  233.         
  234.     INPUTS
  235.         task    - task to be signalled.
  236.         signals - a set of signals to be submitted.
  237.         
  238.     RESULTS
  239.         the signal will show up in the signalled task's
  240.         context.
  241.  
  242.     EXAMPLE
  243.         /* submit the (predefined) abortion signal: */
  244.         TSignal(task, TTASK_SIG_ABORT);
  245.  
  246.     NOTES
  247.         it is valid to apply this function to both the caller's
  248.         own task as well as to foreign tasks.
  249.     
  250.     SEE ALSO
  251.         TSetSignal(), TWait()
  252.  
  253.  
  254. teklib/TSetSignal
  255.  
  256.     NAME
  257.         TSetSignal - set and get a task's signals.
  258.     
  259.     SYNOPSIS 
  260.         oldsignals = TSetSignal(task, newsignals, sigmask);
  261.                                 TAPTR TUINT       TUINT
  262.         
  263.     FUNCTION
  264.         set (and get) task's signals state
  265.         
  266.     INPUTS
  267.         task       - task
  268.         newsignals - new set of signals
  269.         sigmask    - signal bits to be affected
  270.  
  271.     EXAMPLES
  272.         /* get the current state of all signals, but do not modify them */
  273.         signals = TSetSignal(task, 0, 0);
  274.  
  275.         /* clear the pre-defined abortion signal */
  276.         TSetSignal(task, 0, TTASK_SIG_ABORT);
  277.         
  278.     NOTES
  279.         it is valid to apply this function to the caller's own task as
  280.         well as to another task. note, however, that the results may be
  281.         confusing when a foreign context is being addressed: with this
  282.         function it would be possible to wakeup a foreign task with the
  283.         affecting signals being removed from its current signal state.
  284.  
  285.     SEE ALSO
  286.         TSignal(), TWait()
  287.  
  288.  
  289. teklib/TWait
  290.     
  291.     NAME
  292.         TWait - wait for a set of signals.
  293.  
  294.     SYNOPSIS 
  295.         signals = TWait(task, sigmask)
  296.         TUINT           TAPTR TUINT
  297.  
  298.     FUNCTION
  299.         suspend task until one or more of the specified
  300.         signals arrive. those bits will be cleared from
  301.         the task's context when the function returns.
  302.         
  303.     INPUTS
  304.         task    - task, this MUST refer to the caller's context
  305.         sigmask - mask of signals to wait for. if sigmask is 0,
  306.                   this function will return immediately.
  307.  
  308.     RESULTS
  309.         signals - signals that caused returning
  310.  
  311.     NOTES
  312.         if applied not to the caller's own task, the results are
  313.         entirely undefined, and it will likely break your software.
  314.  
  315.     SEE ALSO
  316.         TTimedWait(), TWaitPort(), TSignal()
  317.  
  318.  
  319. teklib/TTimedWait
  320.     
  321.     NAME
  322.         TTimedWait - wait for a set of signals, with timeout
  323.  
  324.     SYNOPSIS 
  325.         signals = TTimedWait(task, sigmask, timeout)
  326.         TUINT                TAPTR TUINT    TTIME*
  327.  
  328.     FUNCTION
  329.         suspend task to wait for a set of signals, or for a timeout.
  330.         any signals causing this function to return will be returned
  331.         to the caller and cleared from the task's set of signals. if
  332.         a timeout caused the return, the return value will be 0.
  333.         if timeout is TNULL or (timeout->sec and timeout->usec) are
  334.         zero, this function is equivalent to TWait().
  335.         
  336.     INPUTS
  337.         task    - task, this MUST refer to the caller's context
  338.         sigmask - mask of signals to wait for
  339.         timeout - pointer to a TTIME specifier
  340.         
  341.     RESULTS
  342.         signals - signals that caused returning, or 0 if timeout
  343.  
  344.     NOTES
  345.         if applied to not the caller's own task, the results are
  346.         entirely undefined, and it will likely break your software.
  347.  
  348.     SEE ALSO
  349.         TWait(), TWaitPort(), TSignal()
  350.  
  351.  
  352. teklib/TInitLock
  353.  
  354.     NAME
  355.         TInitLock - initialize a task lock
  356.  
  357.     SYNOPSIS
  358.         success = TInitLock(task, lock,  tags);
  359.         TBOOL               TAPTR TLOCK* TTAGITEM*
  360.  
  361.     FUNCTION    
  362.         initialize a task lock structure. a task lock is an
  363.         atomic cross-task protection mechanism. after initialization,
  364.         the object has no owner and is in unlocked state.
  365.  
  366.     INPUTS
  367.         task    - caller's own task.
  368.         lock    - pointer to a TLOCK structure.
  369.         tags    - pointer to an array of tag items.
  370.  
  371.     TAGS
  372.         none defined yet.
  373.  
  374.     RESULTS
  375.         success - TTRUE if initialization was successful, else TFALSE
  376.  
  377.     NOTES
  378.         a lock is destroyed with a call to TDestroy(). results are
  379.         undefined if a lock is destroyed in locked state. any call to
  380.         TLock() per calling context must be empaired with exactly
  381.         one matching call to TUnlock().
  382.  
  383.     SEE ALSO
  384.         TLock(), TUnlock(), TDestroy()
  385.  
  386.  
  387. teklib/TLock
  388.  
  389.     NAME
  390.         TLock - gain exclusive access to a task lock.
  391.  
  392.     SYNOPSIS
  393.         TLock(lock);
  394.               TLOCK*
  395.  
  396.     FUNCTION
  397.         gain exclusive access to a task lock. if another task is
  398.         currenty holding the lock, the caller will block until the
  399.         lock is released. if no other task holds the lock, this function
  400.         will return immediately with exclusive access to the lock.
  401.  
  402.         this function is recurisve (or 'nesting'), i.e. it may be called
  403.         again in the caller's context when the lock is already held in
  404.         the caller's context. in that case an internal counter is
  405.         increased, and this function will return immediately. each call
  406.         per context must be empaired with exactly one matching call
  407.         to TUnlock(), which will decrease the counter. finally, when
  408.         the counter reaches zero, the lock is actually released.
  409.  
  410.     INPUTS
  411.         lock    - pointer to a TLOCK structure, initialized with
  412.                   TInitLock()
  413.  
  414.     RESULTS
  415.         none
  416.  
  417.     SEE ALSO
  418.         TUnlock(), TInitLock()
  419.  
  420.  
  421. teklib/TUnlock
  422.  
  423.     NAME
  424.         TUnlock - release access to a task lock.
  425.  
  426.     SYNOPSIS
  427.         TUnlock(lock);
  428.                 TLOCK*
  429.  
  430.     FUNCTION
  431.         release access to a task lock, which was previously obtained with
  432.         a call to TLock(). see the function description there.
  433.  
  434.     INPUTS
  435.         lock    - pointer to a TLOCK structure, initialized with
  436.                   TInitLock()
  437.  
  438.     RESULTS
  439.         none
  440.  
  441.     SEE ALSO
  442.         TLock(), TInitLock()
  443.  
  444.  
  445. teklib/TCreatePort
  446.  
  447.     NAME
  448.         TCreatePort - create a messageport.
  449.  
  450.     SYNOPSIS 
  451.         port = TCreatePort(task, tags)
  452.         TPORT*             TAPTR TTAGITEM*
  453.     
  454.     FUNCTION
  455.         allocate a signal from the given task, and create and initialize
  456.         a port for message communication, which will belong to the
  457.         task's context. 
  458.         
  459.     INPUTS
  460.         task    - task that will be the owner of the messageport.
  461.                   this should be the caller's own task context.
  462.         taglist - pointer to an array of tag items
  463.  
  464.     TAGS
  465.         TTask_MMU, TAPTR
  466.             pointer to a memory management unit to allocate the port
  467.             structures from. default: the task's heap memory manager.
  468.  
  469.     RESULTS
  470.         port    - messageport created, or TNULL on failure.
  471.  
  472.     NOTES
  473.         - a port is destroyed with a call to TDestroy().
  474.         
  475.         - currently (v0.3) it is valid to create a messageport for a
  476.           foreign task, but this should be rarely ever needed, and
  477.           may result in a confusing application design. do not rely
  478.           on this. future versions might limit this function strictly
  479.           to the caller's own task context.
  480.                 
  481.     SEE ALSO
  482.         TWaitPort(), TPutMsg(), TPutReplyMsg(), TDestroy()
  483.  
  484.  
  485. teklib/TWaitPort
  486.  
  487.     NAME
  488.         TWaitPort - wait for a port to be non-empty
  489.             
  490.     SYNOPSIS 
  491.         TWaitPort(msgport)
  492.                   TPORT*
  493.  
  494.     FUNCTION
  495.         suspend a messageport's owner task until a message is
  496.         present at its message queue. when a message is already
  497.         present, return immediately.
  498.  
  499.     INPUTS
  500.         msgport  - messageport. this port must be owned by the
  501.                    caller's context.
  502.     
  503.     RESULTS
  504.         none
  505.  
  506.     NOTES
  507.         if the port does not belong to to the caller's own task context,
  508.         the results are entirely undefined, and it will likely break
  509.         your software.
  510.  
  511.     SEE ALSO
  512.         TCreatePort(), TWait(), TGetMsg()
  513.  
  514.  
  515. teklib/TTimeDelay
  516.  
  517.     NAME
  518.         TTimeDelay - sleep
  519.                
  520.     SYNOPSIS
  521.         TTimeDelay(task, time)
  522.                    TAPTR TTIME*
  523.     
  524.     FUNCTION
  525.         suspend the caller's task and sleep for the specified time.
  526.  
  527.     INPUTS
  528.         task    - task handle referring to the caller's context.
  529.         time    - time structure
  530.     
  531.     SEE ALSO
  532.         TTimeQuery(), TCreateTask()
  533.  
  534.  
  535. teklib/TTimeQuery
  536.  
  537.     NAME
  538.         TTimeQuery - query task timer
  539.                
  540.     SYNOPSIS
  541.         TTimeQuery(task, time)
  542.                    TAPTR TTIME*
  543.     
  544.     FUNCTION
  545.         this function queries a task's inbuilt timer and inserts the
  546.         time elapsed since task creation into the specified time
  547.         structure. 
  548.  
  549.     INPUTS
  550.         task    - task handle to query.
  551.         time    - time structure.
  552.     
  553.     NOTES
  554.         - a task's timer is initialized to zero when its task is created,
  555.           therefore it measures the task's lifetime.
  556.         
  557.         - it is valid to query a foreign task's timer, i.e. the task
  558.           handle does not need to refer to the caller's context.
  559.     
  560.     SEE ALSO
  561.         TTimeReset(), TTimeDelay(), TCreateTask()
  562.  
  563.  
  564. teklib/TTimeReset
  565.  
  566.     NAME
  567.         TTimeReset - reset task timer
  568.                
  569.     SYNOPSIS
  570.         TTimeReset(task)
  571.                    TAPTR
  572.     
  573.     FUNCTION
  574.         this function resets the given task's inbuilt timer to zero.
  575.  
  576.     INPUTS
  577.         task    - task to reset
  578.     
  579.     SEE ALSO
  580.         TTimeQuery(), TTimeDelay(), TCreateTask()
  581.  
  582.  
  583. teklib/TGetRandomSeed
  584.  
  585.     NAME
  586.         TGetRandomSeed - get a seed value
  587.  
  588.     SYNOPSIS
  589.         seed = TGetRandomSeed(task)
  590.         TUINT                 TAPTR
  591.  
  592.     FUNCTION
  593.         generate a random seed number.
  594.     
  595.     INPUTS
  596.         task - task handle to query
  597.  
  598.     RESULTS        
  599.         seed - seed value for random number generation
  600.  
  601.     NOTES
  602.         currently (v0.3) a seed number is generated from a task's
  603.         individual timer, but the quality of this value may differ
  604.         on different hosting environments, and may not be sufficient
  605.         for advanced purposes, such as crypto key generation. 
  606.  
  607.     SEE ALSO
  608.         TGetRandom(), TTimeQuery(), TCreateTask()
  609.  
  610.  
  611. teklib/TTaskAlloc
  612.  
  613.     NAME
  614.         TTaskAlloc - allocate memory from a task
  615.  
  616.     SYNOPSIS
  617.         mem = TTaskAlloc(task, size)
  618.         TAPTR            TAPTR TUINT
  619.  
  620.     FUNCTION
  621.         allocate memory from a task's inbuilt heap memory manager.
  622.     
  623.     INPUTS
  624.         task - task handle to allocate from
  625.         size - size of the requested block of memory [bytes]
  626.  
  627.     RESULTS        
  628.         mem  - pointer to memory, or TNULL if memory exhausted.
  629.  
  630.     NOTES
  631.         - a task's heap memory manager implements thread-safety and
  632.           cleanup handling by default. unless you do not specify a
  633.           user MMU upon task creation, you may safely allocate from
  634.           foreign tasks, and allocations will be freed automatically
  635.           when their respective task exits.
  636.  
  637.         - this function is currently (v0.3) being implemented as
  638.           a macro, redirecting the call to TMMUAlloc() on a task's
  639.           heap MMU.
  640.  
  641.     SEE ALSO
  642.         TTaskFree(), TTaskAlloc0(), TTaskRealloc(), TTaskGetSize(),
  643.         TCreateTask()
  644.  
  645.  
  646. teklib/TTaskAlloc0
  647.  
  648.     NAME
  649.         TTaskAlloc0 - allocate blank memory from a task
  650.  
  651.     SYNOPSIS
  652.         mem = TTaskAlloc0(task, size)
  653.         TAPTR             TAPTR TUINT
  654.  
  655.     FUNCTION
  656.         allocate blank memory from a task's inbuilt heap memory manager,
  657.         i.e. the allocated block will be cleared with zero-bytes.
  658.     
  659.     INPUTS
  660.         task - task handle to allocate from
  661.         size - size of the requested block of memory [bytes]
  662.  
  663.     RESULTS        
  664.         mem  - pointer to memory, or TNULL if memory exhausted.
  665.  
  666.     NOTES
  667.         - see annotations for TTaskAlloc().
  668.  
  669.         - this function is currently (v0.3) being implemented as
  670.           a macro, redirecting the call to TMMUAlloc0() on a task's
  671.           heap MMU.
  672.  
  673.     SEE ALSO
  674.         TTaskFree(), TTaskAlloc()
  675.  
  676.  
  677. teklib/TTaskFree
  678.  
  679.     NAME
  680.         TTaskFree - return memory to a task.
  681.  
  682.     SYNOPSIS
  683.         TTaskFree(task, mem)
  684.                   TAPTR TAPTR
  685.  
  686.     FUNCTION
  687.         return an allocation to a task's heap memory manager.
  688.     
  689.     INPUTS
  690.         task - task handle to allocate from
  691.         mem  - pointer to an allocation made from a task
  692.  
  693.     RESULTS        
  694.         none
  695.  
  696.     NOTES
  697.         - see annotations for TTaskAlloc().
  698.  
  699.         - this function is currently (v0.3) being implemented as
  700.           a macro, redirecting the call to TMMUFree() on a task's
  701.           heap MMU.
  702.  
  703.     SEE ALSO
  704.         TTaskAlloc()
  705.  
  706.  
  707. teklib/TTaskRealloc
  708.  
  709.     NAME
  710.         TTaskRealloc - realloc an allocation from a task
  711.  
  712.     SYNOPSIS
  713.         newmem = TTaskRealloc(task, oldmem, newsize)
  714.         TAPTR                 TAPTR TAPTR   TUINT
  715.  
  716.     FUNCTION
  717.         reallocate an allocation previously made from
  718.         a task's heap memory manager.
  719.  
  720.         when the oldmem argument is TNULL, this function tries to
  721.         allocate a new block of the given newsize. when newsize is
  722.         zero and oldmem is given, the block will be freed, and TNULL
  723.         will be returned. when oldmem is TNULL and newsize is zero,
  724.         this function returns TNULL.
  725.     
  726.     INPUTS
  727.         task    - task handle
  728.         oldmem  - pointer to an allocation from the task
  729.         newsize - new size for the reallocated block of memory
  730.  
  731.     RESULTS  
  732.         newmem  - pointer to memory being reallocated, or TNULL.
  733.  
  734.     NOTES
  735.         - reallocation may require that the given block of memory
  736.           needs to be moved in memory, i.e. pointers to this area
  737.           may become invalid.
  738.     
  739.         - see annotations for TTaskAlloc().
  740.  
  741.         - this function is currently (v0.3) being implemented as
  742.           a macro, redirecting the call to TMMURealloc() on a task's
  743.           heap MMU.
  744.  
  745.     SEE ALSO
  746.         TTaskAlloc()
  747.  
  748.  
  749. teklib/TTaskGetSize
  750.  
  751.     NAME
  752.         TTaskGetSize - get size of an allocation from a task.
  753.  
  754.     SYNOPSIS
  755.         size = TTaskGetSize(task, mem)
  756.         TUINT               TAPTR TAPTR
  757.  
  758.     FUNCTION
  759.         return the size of an allocation previously made from
  760.         a task's heap memory manager.
  761.     
  762.     INPUTS
  763.         task - task handle
  764.         mem  - pointer to an allocation made from the task
  765.  
  766.     RESULTS  
  767.         size - size of the allocation [bytes]
  768.  
  769.     NOTES
  770.         - see annotations for TTaskAlloc().
  771.  
  772.         - this function is currently (v0.3) being implemented as
  773.           a macro, redirecting the call to TMMUGetSize() on a task's
  774.           heap MMU.
  775.  
  776.     SEE ALSO
  777.         TTaskAlloc()
  778.  
  779.  
  780. teklib/TTaskAllocMsg
  781.  
  782.     NAME
  783.         TTaskAllocMsg - allocate a message.
  784.  
  785.     SYNOPSIS
  786.         msg = TTaskAllocMsg(task, size)
  787.         TAPTR               TAPTR TUINT
  788.  
  789.     FUNCTION
  790.         allocate a message of the given size from a task.
  791.     
  792.     INPUTS
  793.         task  - task handle
  794.         size  - size of the message [bytes]
  795.     
  796.     RESULTS  
  797.         msg   - pointer to message buffer, or TNULL if out of memory
  798.  
  799.     NOTES
  800.         - the message size can be queried with TGetMsgAttrs().
  801.  
  802.         - this function is currently (v0.3) being implemented as
  803.           a macro, redirecting the call to TMMUAlloc() on a task's
  804.           message MMU.
  805.  
  806.     SEE ALSO
  807.         TFreeMsg(), TReplyMsg(), TAckMsg(), TDropMsg(), TGetMsgAttrs(),
  808.         TMMUAlloc(), TSendMsg()
  809.  
  810.  
  811. teklib/TTaskBaseTask
  812.  
  813.     NAME
  814.         TTaskBaseTask - get base task handle.
  815.  
  816.     SYNOPSIS
  817.         basetask = TTaskBaseTask(task)
  818.         TAPTR                    TAPTR
  819.  
  820.     FUNCTION
  821.         return a pointer to the root task context of a TEKlib framework.
  822.         the pointer to the base task handle is carried in each of its
  823.         childs. it is also valid to apply this function to the basetask
  824.         itself.
  825.     
  826.     INPUTS
  827.         task      - a task handle
  828.     
  829.     RESULTS  
  830.         basetask  - pointer to the application framework's base task
  831.  
  832.     NOTES
  833.         this function is currently (v0.3) being implemented as a macro.
  834.  
  835.     SEE ALSO
  836.         TCreateTask()
  837.  
  838.  
  839. teklib/TTaskHeapMMU
  840.  
  841.     NAME
  842.         TTaskHeapMMU - get a task's heap memory manager.
  843.  
  844.     SYNOPSIS
  845.         heapmmu = TTaskHeapMMU(task)
  846.         TAPTR                  TAPTR
  847.  
  848.     FUNCTION
  849.         return a pointer to a task's heap memory manager.
  850.     
  851.     INPUTS
  852.         task      - task handle
  853.     
  854.     RESULTS  
  855.         heapmmu   - pointer to the task's heap MMU.
  856.  
  857.     NOTES
  858.         this function is currently (v0.3) being implemented as a macro.
  859.  
  860.     SEE ALSO
  861.         TCreateTask(), TTaskAlloc(), TTaskMsgMMU(), TInitMMU()
  862.  
  863.  
  864. teklib/TTaskMsgMMU
  865.  
  866.     NAME
  867.         TTaskMsgMMU - get a task's message memory manager.
  868.  
  869.     SYNOPSIS
  870.         msgmmu = TTaskMsgMMU(task)
  871.         TAPTR                TAPTR
  872.  
  873.     FUNCTION
  874.         return a pointer to a task's message memory manager.
  875.     
  876.     INPUTS
  877.         task    - task handle
  878.     
  879.     RESULTS  
  880.         msgmmu  - pointer to the task's message MMU.
  881.  
  882.     NOTES
  883.         this function is currently (v0.3) being implemented as a macro.
  884.  
  885.     SEE ALSO
  886.         TCreateTask(), TTaskAllocMsg(), TTaskHeapMMU(), TInitMMU()
  887.  
  888.  
  889. teklib/TTaskGetData
  890.  
  891.     NAME
  892.         TTaskGetData - get a task's userdata pointer.
  893.  
  894.     SYNOPSIS
  895.         userdata = TTaskGetData(task)
  896.         TAPTR                   TAPTR
  897.  
  898.     FUNCTION
  899.         return a pointer to a task's userdata.
  900.     
  901.     INPUTS
  902.         task     - task handle
  903.     
  904.     RESULTS  
  905.         userdata - pointer to the task's userdata.
  906.  
  907.     NOTES
  908.         this function is currently (v0.3) being implemented as a macro.
  909.  
  910.     SEE ALSO
  911.         TTaskSetData(), TCreateTask()
  912.  
  913.  
  914. teklib/TTaskSetData
  915.  
  916.     NAME
  917.         TTaskSetData - change a task's userdata pointer.
  918.  
  919.     SYNOPSIS
  920.         TTaskSetData(task, userdata)
  921.                      TAPTR TAPTR
  922.  
  923.     FUNCTION
  924.         change a task's userdata pointer.
  925.     
  926.     INPUTS
  927.         task     - task handle
  928.         userdata - arbitrary pointer to user data.
  929.  
  930.     NOTES
  931.         - if you want to modify and query a task's userdata pointer from
  932.           different task contexts during a task's lifetime, you will
  933.           probably need to implement a locking mechanism to ensure data
  934.           integrity. you might find it more reliable to leave the primary
  935.           userdata pointer unmodified, and reference userdata indirectly:
  936.           
  937.           struct taskuserdata
  938.           {
  939.               TLOCK lock;
  940.               TAPTR userdata;
  941.           };
  942.           
  943.           TVOID taskfunc(TAPTR task)
  944.           {
  945.               struct taskuserdata *d = TTaskGetData(task);
  946.               TLock(&d->lock);
  947.               /* set and get and operate on d->userdata pointer safely */
  948.               TUnlock(&d->lock);
  949.           }
  950.  
  951.           you can, however, safely set and get a task's userdata pointer
  952.           inside a task's init function, because the newly created context
  953.           is unknown to other task contexts at this time. there is no
  954.           locking required in a task's init function.
  955.  
  956.         - this function is currently (v0.3) being implemented as a macro.
  957.  
  958.     SEE ALSO
  959.         TTaskGetData(), TCreateTask(), TInitLock()
  960.  
  961.  
  962. teklib/TTaskPort
  963.  
  964.     NAME
  965.         TTaskPort - get a task's messageport.
  966.  
  967.     SYNOPSIS
  968.         port = TTaskPort(task)
  969.         TPORT*           TAPTR
  970.  
  971.     FUNCTION
  972.         return a pointer to a task's messageport.
  973.     
  974.     INPUTS
  975.         task     - task handle
  976.     
  977.     RESULTS
  978.         port     - pointer to task's messageport
  979.  
  980.     NOTES
  981.         this function is currently (v0.3) being implemented as a macro.
  982.  
  983.     SEE ALSO
  984.         TCreateTask(), TCreatePort()
  985.  
  986.  
  987. teklib/TFreeMsg
  988.  
  989.     NAME
  990.         TFreeMsg - free a message.
  991.  
  992.     SYNOPSIS
  993.         TFreeMsg(msg)
  994.                  TAPTR
  995.  
  996.     FUNCTION
  997.         free a message and return its memory to the message memory
  998.         manager it has been allocated from.
  999.         
  1000.         this function may be applied only when a message was allocated
  1001.         but never sent, or when it has been sent as a two-way message
  1002.         with TPutReplyMsg(), and returned to a replyport.
  1003.         
  1004.         one-way messages sent with TPutMsg() are freed transparently
  1005.         with either TAckMsg() or TReplyMsg() at the destination
  1006.         endpoint.
  1007.     
  1008.     INPUTS
  1009.         msg      - message to be freed.
  1010.     
  1011.     NOTES
  1012.         this function is currently (v0.3) being implemented as a macro.
  1013.  
  1014.     SEE ALSO
  1015.         TTaskAllocMsg(), TDropMsg(), TReplyMsg(), TAckMsg(), TPutMsg(),
  1016.         TPutReplyMsg(), TSendMsg()
  1017.  
  1018.  
  1019. teklib/TPutMsg
  1020.  
  1021.     NAME
  1022.         TPutMsg - send a one-way message.
  1023.  
  1024.     SYNOPSIS
  1025.         TPutMsg(msgport, msg)
  1026.                 TPORT*   TAPTR
  1027.  
  1028.     FUNCTION
  1029.         put a one-way message to a messageport. one-way messages
  1030.         do not return to the sender. this function never blocks.
  1031.         
  1032.         messages sent to messageports in the caller's local address
  1033.         space are reliable, whereas messages put to remote ports are
  1034.         not. you may only assume that a one-way message has been
  1035.         successfully delivered to a remote port when you receive a
  1036.         corresponding reply, which in some way needs to be defined
  1037.         elsewhere in your individual protocols.
  1038.  
  1039.         when you don't know whether the addressed messageport
  1040.         is in your local address space or not, you must consider
  1041.         message delivery with this function to be unreliable.
  1042.     
  1043.     INPUTS
  1044.         msgport    - messageport to be addressed.
  1045.         msg        - message to be sent.
  1046.     
  1047.     NOTES
  1048.         messages can be sent reliably with TPutReplyMsg().
  1049.  
  1050.     SEE ALSO
  1051.         TPutReplyMsg(), TGetMsg(), TAckMsg(), TReplyMsg(), TDropMsg(),
  1052.         TTaskAllocMsg(), TFreeMsg(), TSendMsg(), TCreatePort()
  1053.  
  1054.  
  1055. teklib/TPutReplyMsg
  1056.  
  1057.     NAME
  1058.         TPutReplyMsg - send a two-way message.
  1059.  
  1060.     SYNOPSIS
  1061.         TPutReplyMsg(msgport, replyport, msg)
  1062.                      TPORT*   TPORT*     TAPTR
  1063.  
  1064.     FUNCTION
  1065.         put a two-way message to a messageport, with a reply
  1066.         or acknowledgement being delivered to the given replyport.
  1067.         two-way messages always return to the sender. this function
  1068.         never blocks.
  1069.  
  1070.         message delivery to a messageport in local address space
  1071.         is defined to be reliable, and will always succeed. message
  1072.         delivery over unreliable transmission paths (such as TCP/IP
  1073.         network connections), on the other hand, may always fail.
  1074.  
  1075.         this function ensures that the sender will be informed about
  1076.         a message's fate, regardless whether the addressed port is
  1077.         in local address space or not. 
  1078.  
  1079.         messages that could not be delivered (or failed to return)
  1080.         over an unreliable connection will appear on the given
  1081.         replyport with their status set to TMSG_STATUS_FAILED.
  1082.         successful delivery will be indicated with a status set to
  1083.         TMSG_STATUS_REPLIED or TMSG_STATUS_ACKD (depending on the
  1084.         reply method). the message status can be queried with
  1085.         TGetMsgAttrs().
  1086.  
  1087.         after the message arrived at its replyport, it usually needs
  1088.         be freed with TFreeMsg(). it is possible, however, to reuse
  1089.         a message.
  1090.  
  1091.     INPUTS
  1092.         msgport    - messageport to be addressed.
  1093.         replyport  - replyport to which the message will be returned.
  1094.         msg        - message to be sent.
  1095.     
  1096.     SEE ALSO
  1097.         TPutMsg(), TGetMsg(), TAckMsg(), TReplyMsg(), TDropMsg(),
  1098.         TTaskAllocMsg(), TFreeMsg(), TSendMsg(), TCreatePort()
  1099.  
  1100.  
  1101. teklib/TGetMsg
  1102.  
  1103.     NAME
  1104.         TGetMsg - get message.
  1105.  
  1106.     SYNOPSIS
  1107.         msg = TGetMsg(msgport)
  1108.         TAPTR         TPORT*
  1109.  
  1110.     FUNCTION
  1111.         unlink the next pending message from a messageport's queue
  1112.         and return it to the caller. this function does not block.
  1113.  
  1114.         a message's status and other attributes can be queried with
  1115.         TGetMsgAttrs().
  1116.     
  1117.     INPUTS
  1118.         msgport    - messageport to get next message from.
  1119.         
  1120.     RESULTS
  1121.         msg        - next pending message, or TNULL if the
  1122.                      messageport queue was empty.
  1123.  
  1124.     SEE ALSO
  1125.         TPutMsg(), TPutReplyMsg(), TAckMsg(), TReplyMsg(),
  1126.         TTaskAllocMsg(), TFreeMsg(), TCreatePort()
  1127.  
  1128.  
  1129. teklib/TAckMsg
  1130.  
  1131.     NAME
  1132.         TAckMsg - acknowledge message.
  1133.  
  1134.     SYNOPSIS
  1135.         TAckMsg(msg)
  1136.                 TAPTR
  1137.  
  1138.     FUNCTION
  1139.         acknowledge a two-way message to its sender, i.e. return
  1140.         it to its sender's replyport.
  1141.  
  1142.         it is safe, however, to apply this function to one-way
  1143.         messages as well; if the message was sent without a reply
  1144.         or acknowledgement expected, it will be silently freed by
  1145.         this function.
  1146.    
  1147.         when a message is returned with this function, the sender
  1148.         must not rely on any modifications made inside the message body.
  1149.         if you want to modify data inside the message and send its
  1150.         modified contents back to the sender, you should use TReplyMsg()
  1151.         instead.
  1152.  
  1153.     INPUTS
  1154.         msg     - message to be acknowledged to its sender
  1155.                   (or to be freed, transparently)
  1156.  
  1157.     SEE ALSO
  1158.         TReplyMsg(), TFreeMsg(), TDropMsg(), TPutMsg(), TPutReplyMsg(),
  1159.         TFreeMsg(), TTaskAllocMsg(), TSendMsg(), TCreatePort()
  1160.  
  1161.  
  1162. teklib/TReplyMsg
  1163.  
  1164.     NAME
  1165.         TReplyMsg - reply message.
  1166.  
  1167.     SYNOPSIS
  1168.         TReplyMsg(msg)
  1169.                   TAPTR
  1170.  
  1171.     FUNCTION
  1172.         reply a two-way message to its sender, i.e. return its entire
  1173.         contents back to its sender's replyport.
  1174.  
  1175.         it is safe, however, to apply this function to one-way
  1176.         messages as well; if the message was sent without a reply
  1177.         or acknowledgement expected, it will be silently freed by
  1178.         this function.
  1179.  
  1180.         use this function for transferring a modified message body
  1181.         back to its sender. if the message was not modified and it is
  1182.         only required to inform the sender that it has been delivered,
  1183.         then you should prefer TAckMsg().
  1184.  
  1185.     INPUTS
  1186.         msg     - message to be replied to its sender.
  1187.                   (or to be freed, transparently)
  1188.  
  1189.     SEE ALSO
  1190.         TAckMsg(), TFreeMsg(), TDropMsg(), TPutMsg(), TPutReplyMsg(),
  1191.         TFreeMsg(), TTaskAllocMsg(), TSendMsg(), TCreatePort()
  1192.  
  1193.  
  1194. teklib/TDropMsg
  1195.  
  1196.     NAME
  1197.         TDropMsg - abandon a message.
  1198.  
  1199.     SYNOPSIS
  1200.         TDropMsg(msg)
  1201.                  TAPTR
  1202.  
  1203.     FUNCTION
  1204.         abandon a two-way message, i.e. return it to its replyport with
  1205.         the message status set to TMSG_STATUS_FAILED. this function is
  1206.         not guaranteed to return any modifications made inside the
  1207.         message body, it will only indicate failure.
  1208.  
  1209.         it is safe to apply this function to one-way messages as well;
  1210.         if the message was sent without a reply or acknowledgement
  1211.         expected, it will be silently freed by this function.
  1212.  
  1213.     INPUTS
  1214.         msg     - message to be abandoned.
  1215.         
  1216.     NOTES
  1217.         currently (v0.3), if applied to a remote messageport, this
  1218.         function will not only abandon a single message, but the entire
  1219.         underlying socket proxy. all messages sent after the one being
  1220.         dropped will fail on this network connection, and pending replies
  1221.         will fail after their respective timeout.
  1222.  
  1223.     SEE ALSO
  1224.         TAckMsg(), TReplyMsg(), TFreeMsg(), TPutMsg(), TPutReplyMsg(),
  1225.         TTaskAllocMsg(), TSendMsg(), TCreatePort()
  1226.  
  1227.  
  1228. teklib/TSendMsg
  1229.  
  1230.     NAME
  1231.         TSendMsg - send a message, synchronized
  1232.  
  1233.     SYNOPSIS
  1234.         replymsg = TSendMsg(task, msgport, msg)
  1235.         TAPTR               TAPTR TPORT*   TAPTR
  1236.  
  1237.     FUNCTION
  1238.         this function sends a message two-way, synchronized, and waits
  1239.         for either a reply to return, or for the messageport's timeout.
  1240.         this is currently the only messaging function that may block.
  1241.         
  1242.         the return value will be either set to msg, indicating that the
  1243.         message has been sent and acknowledged/replied successfully,
  1244.         or TNULL, when the message could not be sent or did not return
  1245.         within a remote msgport's timeout.
  1246.  
  1247.     INPUTS
  1248.         task     - task, must refer to the caller's context.
  1249.         msgport  - msgport to address.
  1250.         msg      - message to be sent.
  1251.  
  1252.     RETURNS
  1253.         replymsg - will be set to msg when the message was sent and
  1254.                    returned successfully, otherwise TNULL.
  1255.  
  1256.     SEE ALSO
  1257.         TAckMsg(), TReplyMsg(), TDropMsg(), TFreeMsg(), TPutMsg(),
  1258.         TPutReplyMsg(), TTaskAllocMsg(), TCreatePort(), TFindSockPort()
  1259.  
  1260.  
  1261. teklib/TGetMsgAttrs
  1262.  
  1263.     NAME
  1264.         TGetMsgAttrs - query message attributes.
  1265.  
  1266.     SYNOPSIS
  1267.         numattr = TGetMsgAttrs(msg,  tags)
  1268.         TUINT                  TAPTR TTAGITEM*
  1269.  
  1270.     FUNCTION
  1271.         this function queries a given set of attributes from a message.
  1272.         the attributes will be filled into the taglist's respective
  1273.         variable pointers, and the number of attributes successfully
  1274.         retrieved will be returned to the caller.
  1275.  
  1276.     INPUTS
  1277.         msg     - message to be queried.
  1278.         tags    - pointer to an array of tagitems.
  1279.     
  1280.     RESULTS
  1281.         numattr - number of attributes filled into their respective
  1282.                   variable pointers.
  1283.     
  1284.     TAGS
  1285.         TMsg_Size, TUINT *
  1286.             the variable being pointed to by the tag value will be filled
  1287.             with the size of the message in bytes.
  1288.         
  1289.         TMsg_Status, TUINT *
  1290.             the variable being pointed to by the tag value will be filled
  1291.             with the message status, which can be
  1292.  
  1293.                 TMSG_STATUS_UNDEFINED - message was never sent.
  1294.  
  1295.                 TMSG_STATUS_SENT      - the message has been sent 
  1296.                                         successfully.
  1297.                 
  1298.                 TMSG_STATUS_FAILED    - the message could not be sent or
  1299.                                         failed to return within a given
  1300.                                         timeout period.
  1301.                 
  1302.                 TMSG_STATUS_REPLIED   - the message has been replied
  1303.                                         successfully, and returned to the
  1304.                                         sender.
  1305.                                         
  1306.                 TMSG_STATUS_ACKD      - the message has been acknowledged
  1307.                                         successfully, and returned to the
  1308.                                         sender.
  1309.  
  1310.         TMsg_Sender, TSTRPTR *
  1311.             the variable being pointed to by the tag value will be set to
  1312.             a pointer to a string, which will contain a sender
  1313.             messageport's unique name. this name is currently (v0.3) being
  1314.             composed from the sender's host and port number, such as
  1315.             "192.168.0.77:32452". for messages originating from local
  1316.             address space, this pointer will be set to TNULL.
  1317.             
  1318.             warning: this string pointer is no longer valid after the
  1319.             message has been handed over to TReplyMsg(), TAckMsg(),
  1320.             TFreeMsg(), or TDropMsg().
  1321.             
  1322.         TMsg_SenderHost, TSTRPTR *
  1323.             the variable being pointed to by the tag value will be set to
  1324.             a pointer to a string containing the sender's host, e.g.
  1325.             "192.168.0.77". for messages originating from local address
  1326.             space, this pointer will be set to TNULL.
  1327.  
  1328.             warning: this string pointer is no longer valid after the
  1329.             message has been handed over to TReplyMsg(), TAckMsg(),
  1330.             TFreeMsg(), or TDropMsg().
  1331.             
  1332.         TMsg_SenderPort, TUINT *
  1333.             the variable being pointed to by the tag value will be set to
  1334.             the sender messageport's internet port number, which may range
  1335.             from 0 to 65535. for messages originating from local address
  1336.             space, the portnumber will be set to 0xffffffff.
  1337.  
  1338.     NOTES
  1339.         it would be unwise to assume a specific format for the strings
  1340.         returned by TMsg_Sender or TMsg_SenderHost. currently (v0.3), the
  1341.         string format returned will reflect the ipv4 addressing scheme.
  1342.  
  1343.     SEE ALSO
  1344.         TGetMsg(), TPutMsg(), TPutReplyMsg(), TAckMsg(), TReplyMsg(),
  1345.         TDropMsg(), TFreeMsg(), TTaskAllocMsg(), TSendMsg(), TCreatePort()
  1346.  
  1347.  
  1348. teklib/TGetMsgStatus
  1349.  
  1350.     NAME
  1351.         TGetMsgStatus - get message status.
  1352.  
  1353.     SYNOPSIS
  1354.         status = TGetMsgStatus(msg)
  1355.         TUINT                  TAPTR
  1356.  
  1357.     FUNCTION
  1358.         get a message's delivery status.
  1359.  
  1360.     INPUTS
  1361.         msg     - message to be queried.
  1362.     
  1363.     RESULTS
  1364.         status  - message's delivery status, which can be 
  1365.  
  1366.                   TMSG_STATUS_UNDEFINED - message was never sent.
  1367.  
  1368.                   TMSG_STATUS_SENT      - the message has been sent 
  1369.                                           successfully.
  1370.              
  1371.                   TMSG_STATUS_FAILED    - the message could not be sent or
  1372.                                           failed to return within a given
  1373.                                           timeout period.
  1374.                 
  1375.                   TMSG_STATUS_REPLIED   - the message has been replied
  1376.                                           successfully, and returned to the
  1377.                                           sender.
  1378.  
  1379.                   TMSG_STATUS_ACKD      - the message has been acknowledged
  1380.                                           successfully, and returned to the
  1381.                                           sender.
  1382.  
  1383.     NOTES
  1384.         this function is currently being (v0.3) implemented as a macro.
  1385.  
  1386.     SEE ALSO
  1387.         TGetMsgAttrs(), TGetMsgSize()
  1388.  
  1389.  
  1390. teklib/TGetMsgSize
  1391.  
  1392.     NAME
  1393.         TGetMsgSize - get message size.
  1394.  
  1395.     SYNOPSIS
  1396.         size = TGetMsgSize(msg)
  1397.         TUINT              TAPTR
  1398.  
  1399.     FUNCTION
  1400.         get message size.
  1401.  
  1402.     INPUTS
  1403.         msg     - message to be queried.
  1404.     
  1405.     RESULTS
  1406.         size    - size of the message in bytes.
  1407.  
  1408.     NOTES
  1409.         this function is currently being (v0.3) implemented as a macro.
  1410.  
  1411.     SEE ALSO
  1412.         TGetMsgAttrs(), TGetMsgStatus()
  1413.  
  1414.  
  1415. teklib/TAddHead
  1416.  
  1417.     NAME
  1418.         TAddHead - add a node at the head of a list.
  1419.         
  1420.     SYNOPSIS
  1421.         TAddHead(list,  node)
  1422.                  TLIST* TNODE*
  1423.     
  1424.     FUNCTION
  1425.         add a node at the head of a doubly linked list.
  1426.    
  1427.     INPUTS
  1428.         list - pointer to a list header.
  1429.         node - pointer to a node to be inserted.
  1430.  
  1431.     SEE ALSO
  1432.         TAddTail(), TInitList()
  1433.         
  1434.  
  1435. teklib/TAddTail
  1436.  
  1437.     NAME
  1438.         TAddTail - add a node at the tail of a list.
  1439.         
  1440.     SYNOPSIS
  1441.         TAddTail(list,  node)
  1442.                  TLIST* TNODE*
  1443.     
  1444.     FUNCTION
  1445.         add a node at the tail of a doubly linked list.
  1446.    
  1447.     INPUTS
  1448.         list - pointer to a list header.
  1449.         node - pointer to a node to be inserted.
  1450.     
  1451.     SEE ALSO
  1452.         TAddHead(), TInitList()
  1453.         
  1454.  
  1455. teklib/TInsert
  1456.  
  1457.     NAME
  1458.         TInsert - insert a node into a list.
  1459.                
  1460.     SYNOPSIS
  1461.         TInsert(list,  node,  listnode)
  1462.                 TLIST* TNODE* TNODE *
  1463.     
  1464.     FUNCTION
  1465.         insert a node into a doubly linked list after the given
  1466.         listnode. if listnode == TNULL, this function is equivalent
  1467.         to TAddFirst().
  1468.    
  1469.     INPUTS
  1470.         list - pointer to a list header.
  1471.         node - pointer to a node to be inserted.
  1472.         listnode - pointer to a node after which to insert.
  1473.     
  1474.     SEE ALSO
  1475.         TInitList(), TRemove(), TAddHead()
  1476.         
  1477.  
  1478. teklib/TRemove
  1479.  
  1480.     NAME
  1481.         TRemove - unlink a node from a list.
  1482.                
  1483.     SYNOPSIS
  1484.         TRemove(node)
  1485.                 TNODE*
  1486.     
  1487.     FUNCTION
  1488.         remove, i.e. unlink a node from whatever list it might
  1489.         be linked into.
  1490.    
  1491.     INPUTS
  1492.         list - pointer to a list header.
  1493.         node - pointer to a node to be removed.
  1494.     
  1495.     NOTES
  1496.         calling this function with a node not being part of a list
  1497.         may be fatal.
  1498.     
  1499.     SEE ALSO
  1500.         TRemHead(), TRemTail(), TInitList()
  1501.         
  1502.  
  1503. teklib/TRemHead
  1504.  
  1505.     NAME
  1506.         TRemHead - unlink the first node of a list.
  1507.                
  1508.     SYNOPSIS
  1509.         node = TRemHead(list)
  1510.         TNODE*          TLIST*
  1511.     
  1512.     FUNCTION
  1513.         remove, i.e. unlink and return the first node from
  1514.         a doubly linked list.
  1515.    
  1516.     INPUTS
  1517.         list - pointer to a list header.
  1518.     
  1519.     RESULTS
  1520.         node - pointer to the node that has been removed, or
  1521.                TNULL when the list was empty.
  1522.     
  1523.     SEE ALSO
  1524.         TRemTail(), TRemove(), TInitList()
  1525.         
  1526.  
  1527. teklib/TRemTail
  1528.  
  1529.     NAME
  1530.         TRemTail - unlink the last node of a list.
  1531.                
  1532.     SYNOPSIS
  1533.         node = TRemTail(list)
  1534.         TNODE*          TLIST*
  1535.     
  1536.     FUNCTION
  1537.         remove, i.e. unlink and return the last node from
  1538.         a doubly linked list.
  1539.    
  1540.     INPUTS
  1541.         list - pointer to a list header.
  1542.     
  1543.     RESULTS
  1544.         node - pointer to the node that has been removed, or
  1545.                TNULL when the list was empty.
  1546.     
  1547.     SEE ALSO
  1548.         TRemHead(), TRemove(), TInitList()
  1549.  
  1550.  
  1551. teklib/TSeekNode
  1552.  
  1553.     NAME
  1554.         TSeekNode - seek node.
  1555.                
  1556.     SYNOPSIS
  1557.         node = TSeekNode(node,  numsteps)
  1558.         TNODE*           TNODE* TINT
  1559.     
  1560.     FUNCTION
  1561.         starting from node, seek by the given number of steps
  1562.         either forwards (steps > 0) or backwards (steps < 0).
  1563.         when steps == 0, the current node is returned. when the
  1564.         list is seeked past end or before start, TNULL will be
  1565.         returned.
  1566.    
  1567.     INPUTS
  1568.         node  - pointer to a node inside a list.
  1569.         steps - number of steps to be seeked.
  1570.     
  1571.     RESULTS
  1572.         node - pointer to the node reached, or TNULL.
  1573.     
  1574.     SEE ALSO
  1575.         TInitList()
  1576.  
  1577.  
  1578. teklib/TInitList
  1579.  
  1580.     NAME
  1581.         TInitList - prepare a list header structure.
  1582.         
  1583.     SYNOPSIS
  1584.         TInitList(list)
  1585.                   TLIST*
  1586.     
  1587.     FUNCTION
  1588.         prepare a list header structure. the list
  1589.         will be empty and ready for usage.
  1590.    
  1591.     INPUTS
  1592.         list - pointer to an uninitialized list structure.
  1593.         
  1594.     NOTE
  1595.         this function is currently (v0.3) being implemented as
  1596.         a macro.
  1597.  
  1598.     SEE ALSO
  1599.         TAddHead(), TAddTail(), TInsert(), TRemove(), TRemHead(),
  1600.         TRemTail(), TSeekNode(), TFirstNode(), TLastNode(),
  1601.         TListEmpty()
  1602.  
  1603.  
  1604. teklib/TFirstNode
  1605.  
  1606.     NAME
  1607.         TFirstNode - get first node of a list.
  1608.                
  1609.     SYNOPSIS
  1610.         node = TFirstNode(list)
  1611.         TNODE*            TLIST*
  1612.     
  1613.     FUNCTION
  1614.         return the first node in a list, or TNULL when the list
  1615.         is empty.
  1616.    
  1617.     INPUTS
  1618.         list - pointer to a list header.
  1619.     
  1620.     RESULTS
  1621.         node - pointer to the first node in a list, or TNULL.
  1622.  
  1623.     NOTE
  1624.         this function is currently (v0.3) being implemented as
  1625.         a macro.
  1626.     
  1627.     SEE ALSO
  1628.         TLastNode(), TListEmpty(), TInitList()
  1629.  
  1630.  
  1631. teklib/TLastNode
  1632.  
  1633.     NAME
  1634.         TLastNode - get last node of a list.
  1635.                
  1636.     SYNOPSIS
  1637.         node = TLastNode(list)
  1638.         TNODE*           TLIST*
  1639.     
  1640.     FUNCTION
  1641.         return the last node in a list, or TNULL when the list
  1642.         is empty.
  1643.    
  1644.     INPUTS
  1645.         list - pointer to a list header.
  1646.  
  1647.     RESULTS
  1648.         node - pointer to the last node in a list, or TNULL.
  1649.     
  1650.     NOTE
  1651.         this function is currently (v0.3) being implemented as
  1652.         a macro.
  1653.  
  1654.     SEE ALSO
  1655.         TFirstNode(), TListEmpty(), TInitList()
  1656.  
  1657.  
  1658. teklib/TListEmpty
  1659.  
  1660.     NAME
  1661.         TListEmpty - test if a list is empty.
  1662.                
  1663.     SYNOPSIS
  1664.         isempty = TListEmpty(list)
  1665.         TBOOL                TLIST*
  1666.     
  1667.     FUNCTION
  1668.         test if a list is empty.
  1669.    
  1670.     INPUTS
  1671.         list    - pointer to a list header.
  1672.  
  1673.     RESULTS
  1674.         isempty - boolean, TTRUE when there are no nodes linked to
  1675.                   the list.
  1676.  
  1677.     NOTE
  1678.         this function is currently (v0.3) being implemented as
  1679.         a macro.
  1680.  
  1681.     SEE ALSO
  1682.         TFirstNode(), TInitList()
  1683.  
  1684.  
  1685. teklib/TGetTagValue
  1686.  
  1687.     NAME
  1688.         TGetTagValue - get tag value from a tag list
  1689.         
  1690.     SYNOPSIS
  1691.         value = TGetTagValue(tag, defaultvalue, taglist)
  1692.         TTAG                 TTAG TTAG          TTAGITEM* 
  1693.     
  1694.     FUNCTION
  1695.         parse a list of tag items and return the matching
  1696.         tag value. if the specified tag is not contained in
  1697.         the list, return the default value.
  1698.    
  1699.     INPUTS
  1700.         tag          - tag to be queried.
  1701.         defaultvalue - default tag value.
  1702.         taglist      - pointer to a list of tag items.
  1703.  
  1704.     RESULTS
  1705.         value - the value associated with the queried tag, if found
  1706.                 in the taglist, otherwise the default value.
  1707.  
  1708.     SEE ALSO
  1709.         TGetTagArray(), TInitTags(), TAddTag()
  1710.  
  1711.  
  1712. teklib/TGetTagArray
  1713.  
  1714.     NAME
  1715.         TGetTagArray - get an array of tag values from a tag list
  1716.         
  1717.     SYNOPSIS
  1718.         numtags = TGetTagArray(taglist,  tagarray)
  1719.         TUINT                  TTAGITEM* TTAG*
  1720.  
  1721.     FUNCTION
  1722.         this function parses an array of tag items and a taglist, and
  1723.         transfers the values of all matching tags from the taglist into
  1724.         the variables referenced by pointers in the tag array. both
  1725.         the tag array and the taglist must be concluded with TTAG_DONE.
  1726.         the number of tags that have been retrieved will be returned to
  1727.         the caller.
  1728.     
  1729.     EXAMPLE
  1730.         TTAG one = 1; two = 2; three = 3;  /* default values */
  1731.         
  1732.         num = TGetTagArray(taglist, 
  1733.                 MYTAG_One, (TTAG) &one,
  1734.                 MYTAG_Two, (TTAG) &two,
  1735.                 MYTAG_Three, (TTAG) &three,
  1736.                 TTAG_DONE);
  1737.    
  1738.     INPUTS
  1739.         taglist  - pointer to a list of tag items.
  1740.         tagarray - pointer to an array of pairs of
  1741.                    tag and variable pointer each.
  1742.  
  1743.     RESULTS
  1744.         numtags - number of tags that have been retrieved
  1745.                   from the taglist, and inserted to their
  1746.                   respective variables.
  1747.  
  1748.     SEE ALSO
  1749.         TGetTagValue(), TInitTags(), TAddTag()
  1750.  
  1751.  
  1752. teklib/TInitTags
  1753.  
  1754.     NAME
  1755.         TInitTags - init an array of tagitems.
  1756.         
  1757.     SYNOPSIS
  1758.         TInitTags(taglist)
  1759.                   TTAGITEM*
  1760.     
  1761.     FUNCTION
  1762.         prepare an array of tagitems to be filled with tag
  1763.         attributes, using TAddTag().
  1764.    
  1765.     INPUTS
  1766.         taglist  - pointer to an array of tag items
  1767.  
  1768.     NOTE
  1769.         this function is currently (v0.3) being implemented as
  1770.         a macro.
  1771.  
  1772.     SEE ALSO
  1773.         TAddTag(), TGetTagValue, TGetTagArray()
  1774.  
  1775.  
  1776. teklib/TAddTag
  1777.  
  1778.     NAME
  1779.         TAddTag - add a tag/value pair to a taglist.
  1780.         
  1781.     SYNOPSIS
  1782.         TAddTag(taglist,  tag, value)
  1783.                 TTAGITEM* TTAG TTAG
  1784.     
  1785.     FUNCTION
  1786.         add a single tag/value pair to a list of tag items.
  1787.  
  1788.         your taglist must be dimensioned to contain at least
  1789.         one more item than the number of items being added
  1790.         with this function.
  1791.  
  1792.     INPUTS
  1793.         taglist  - pointer to an array of tag items
  1794.         tag      - tag identifier
  1795.         value    - tag value
  1796.  
  1797.     NOTE
  1798.         - this function is currently (v0.3) being implemented as
  1799.           a macro.
  1800.         
  1801.         - this is a convenience macro. it may save a few keystrokes,
  1802.           but it is suboptimal. it is quicker to fill a tag list
  1803.           manually.
  1804.  
  1805.     SEE ALSO
  1806.         TInitTags(), TGetTagValue(), TGetTagArray()
  1807.  
  1808.  
  1809. teklib/TGetRandom
  1810.  
  1811.     NAME
  1812.         TGetRandom - generate signed random number
  1813.  
  1814.     SYNOPSIS
  1815.         random = TGetRandom(seed)
  1816.         TINT                TINT
  1817.  
  1818.     FUNCTION 
  1819.         generate a 32 bit pseudo random number, which will be
  1820.         computed from the seed value. the number returned will
  1821.         be in the range from -2147483648 to 2147483647.
  1822.         
  1823.         typically the returned number will be fed back to
  1824.         TGetRandom() as the new seed value for the next number
  1825.         generation cycle.
  1826.         
  1827.     EXAMPLE
  1828.         /* generate a random number from 0 to 343 */
  1829.     
  1830.         TINT seed, rand_value;       
  1831.         rand_value = (seed = TGetRandom(seed)) % 344;
  1832.         
  1833.     INPUTS
  1834.         seed   - a seed value for the number generator.
  1835.  
  1836.     RESULTS        
  1837.         random - a pseudo random number.
  1838.  
  1839.     NOTES
  1840.         - the numbers generated by this function are not random.
  1841.           a number series is always fully determined by its initial
  1842.           seed value. the series only appears to be random in an
  1843.           arbitrary short range.
  1844.  
  1845.         - for useful random numbers the seed variable should be
  1846.           initialized with a hardly deterministic number.
  1847.     
  1848.     SEE ALSO
  1849.         TGetRandomSeed()
  1850.  
  1851.  
  1852. teklib/TMemCopy
  1853.  
  1854.     NAME
  1855.         TMemCopy - copy a block of memory.
  1856.  
  1857.     SYNOPSIS
  1858.         TMemCopy(source, dest, numbytes)
  1859.                  TAPTR   TAPTR TUINT
  1860.  
  1861.     FUNCTION
  1862.         copy a block of memory, i.e. the given number of bytes
  1863.         from source to dest.
  1864.  
  1865.     INPUTS
  1866.         source   - source address
  1867.         dest     - destination address
  1868.         numbytes - number of bytes to copy
  1869.  
  1870.     NOTES
  1871.         you may not rely on overlapping copies to work with
  1872.         this function.
  1873.     
  1874.     SEE ALSO
  1875.         TMemCopy32(), TMemFill()
  1876.  
  1877.  
  1878. teklib/TMemFill
  1879.  
  1880.     NAME
  1881.         TMemFill - fill a block of memory.
  1882.  
  1883.     SYNOPSIS
  1884.         TMemFill(start, numbytes, fillval)
  1885.                  TAPTR  TUINT     TUINT
  1886.  
  1887.     FUNCTION
  1888.         fill a range of memory with a character fill value.
  1889.  
  1890.     INPUTS
  1891.         start    - start address
  1892.         numbytes - number of bytes to fill
  1893.         fillval  - character to fill in
  1894.  
  1895.     SEE ALSO
  1896.         TMemFill32(), TMemCopy()
  1897.  
  1898.  
  1899. teklib/TMemCopy32
  1900.  
  1901.     NAME
  1902.         TMemCopy32 - copy a block of memory, aligned
  1903.  
  1904.     SYNOPSIS
  1905.         TMemCopy32(source, dest, numbytes)
  1906.                    TAPTR   TAPTR TUINT
  1907.  
  1908.     FUNCTION
  1909.         copy a block of memory, i.e. the given number of bytes
  1910.         from source to dest. the source and destination address
  1911.         must be aligned to 32 bit boundaries in memory, and the
  1912.         number of bytes must be 32 bit aligned as well.
  1913.  
  1914.     INPUTS
  1915.         source   - source address, 32bit aligned
  1916.         dest     - destination address, 32bit aligned
  1917.         numbytes - number of bytes to copy, 32bit aligned
  1918.  
  1919.     NOTES
  1920.         you may not rely on overlapping copies to work with
  1921.         this function.
  1922.     
  1923.     SEE ALSO
  1924.         TMemCopy(), TMemFill32()
  1925.  
  1926.  
  1927. teklib/TMemFill32
  1928.  
  1929.     NAME
  1930.         TMemFill - fill a block of memory, aligned
  1931.  
  1932.     SYNOPSIS
  1933.         TMemFill32(start, numbytes, fillval)
  1934.                    TAPTR  TUINT     TUINT
  1935.  
  1936.     FUNCTION
  1937.         fill a range of memory with a 32bit fill value. the 
  1938.         start address and the number of bytes must be aligned
  1939.         to 32 bit.
  1940.  
  1941.     INPUTS
  1942.         start    - start address, 32bit aligned
  1943.         numbytes - number of bytes to fill, 32bit aligned
  1944.         fillval  - 32bit value to fill in
  1945.  
  1946.     SEE ALSO
  1947.         TMemFill(), TMemCopy32()
  1948.  
  1949.  
  1950. teklib/TInitMemHead
  1951.  
  1952.     NAME
  1953.         TInitMemHead - initialize a memheader.
  1954.  
  1955.     SYNOPSIS
  1956.         success = TInitMemHead(memhead,  mem,  size, tags)
  1957.         TBOOL                  TMEMHEAD* TAPTR TUINT TTAGITEM*
  1958.  
  1959.     FUNCTION 
  1960.         initialize a memheader. a memheader is a memory range
  1961.         descriptor that can be used for lowlevel allocation
  1962.         from a static block of memory.
  1963.  
  1964.     INPUTS
  1965.         memhead - pointer to an uninitialized memheader structure
  1966.         mem     - pointer to a block of memory to be used as a
  1967.                   static memory allocation pool
  1968.         size    - size of the memory block [bytes]
  1969.         tags    - pointer to an array of tag items
  1970.  
  1971.     TAGS
  1972.         none defined yet        
  1973.         
  1974.     RESULTS        
  1975.         success  - boolean indicating whether initialization
  1976.                    was successful. TTRUE if the header is ready.
  1977.  
  1978.     EXAMPLE
  1979.         /* setup a memheader at the beginning of a memory block */
  1980.  
  1981.         TUINT8 memory[100000];
  1982.  
  1983.         TInitMemHead((TMEMHEAD *) memory, memory + sizeof(TMEMHEAD),
  1984.             sizeof(memory) - sizeof(TMEMHEAD), TNULL);
  1985.  
  1986.         /* now ((TMEMHEAD *) memory) may be passed to functions like
  1987.            TStaticAlloc() and TStaticRealloc(). */
  1988.  
  1989.     SEE ALSO
  1990.         TStaticAlloc(), TStaticFree(), TStaticRealloc(),
  1991.         TStaticGetSize()
  1992.  
  1993.  
  1994. teklib/TStaticAlloc
  1995.  
  1996.     NAME
  1997.         TStaticAlloc - allocate memory from a static block of memory.
  1998.  
  1999.     SYNOPSIS
  2000.         mem = TStaticAlloc(memhead,  size)
  2001.         TAPTR              TMEMHEAD* TUINT
  2002.  
  2003.     FUNCTION 
  2004.         allocate from a block of static memory, which is described by
  2005.         a memhead structure. returns a block of memory of the given size,
  2006.         or TNULL when the request could not be satisfied.
  2007.  
  2008.     INPUTS
  2009.         memhead - pointer to an initialized memheader structure
  2010.         size    - size of the request [bytes]
  2011.         
  2012.     RESULTS        
  2013.         mem     - memory allocated, or TNULL, when there was no
  2014.                   block of memory of the requested size available.
  2015.  
  2016.     NOTES
  2017.         it is not allowed to pass TNULL or zero for either memhead
  2018.         or size. this function is designed for low overhead.
  2019.     
  2020.     SEE ALSO
  2021.         TInitMemHeadA(), TStaticFree(), TStaticRealloc(),
  2022.         TStaticGetSize()
  2023.  
  2024.  
  2025. teklib/TStaticRealloc
  2026.  
  2027.     NAME
  2028.         TStaticRealloc - reallocate an allocation from static memory.
  2029.  
  2030.     SYNOPSIS
  2031.         newmem = TStaticRealloc(memhead,  oldmem, newsize)
  2032.         TAPTR                   TMEMHEAD* TAPTR   TUINT
  2033.  
  2034.     FUNCTION 
  2035.         resize a block of memory from a static memory allocation to the
  2036.         specified size, and return a pointer to the resized block of
  2037.         memory, or TNULL when the memory block could not be resized. 
  2038.        
  2039.         when a memory block is supplied, and newsize is zero, then
  2040.         the memory block will be returned to the static block of
  2041.         memory, and the result of this function is TNULL.
  2042.         
  2043.         when newsize is nonzero, and the memory block is TNULL, this
  2044.         function will try to allocate a new block of the given size.
  2045.         
  2046.         if mem is TNULL and size is zero, this function will return
  2047.         TNULL.
  2048.  
  2049.     INPUTS
  2050.         memhead - pointer to an initialized memheader structure
  2051.         oldmem  - pointer to a block of memory to be resized
  2052.         newsize - new size of the block [bytes]
  2053.         
  2054.     RESULTS        
  2055.         mem     - resized (or freshly allocated) block of memory,
  2056.                   or TNULL.
  2057.  
  2058.     NOTES
  2059.         - it is not allowed to pass TNULL for the memhead argument.
  2060.  
  2061.         - reallocation may require that the given block of memory
  2062.           needs to be moved in memory, i.e. pointers to this area
  2063.           may become invalid.
  2064.     
  2065.     SEE ALSO
  2066.         TInitMemHeadA(), TStaticAlloc(), TStaticFree(),
  2067.         TStaticGetSize()
  2068.  
  2069.  
  2070. teklib/TStaticFree
  2071.  
  2072.     NAME
  2073.         TStaticFree - return memory to a static block of memory.
  2074.  
  2075.     SYNOPSIS
  2076.         TStaticFree(memhead,  mem)
  2077.                     TMEMHEAD* TAPTR
  2078.  
  2079.     FUNCTION 
  2080.         free a block of memory and return it to the static block
  2081.         of memory it was allocated from.
  2082.  
  2083.     INPUTS
  2084.         memhead - pointer to an initialized memheader structure
  2085.         mem     - pointer to a block of memory to be freed
  2086.         
  2087.     NOTES
  2088.         it is not allowed to pass TNULL or zero for either memhead
  2089.         or mem. this function is designed for low overhead.
  2090.     
  2091.     SEE ALSO
  2092.         TInitMemHeadA(), TStaticAlloc(), TStaticRealloc(),
  2093.         TStaticGetSize()
  2094.  
  2095.  
  2096. teklib/TStaticGetSize
  2097.  
  2098.     NAME
  2099.         TStaticGetSize - get size of an allocation from static memory.
  2100.  
  2101.     SYNOPSIS
  2102.         size = TStaticGetSize(memhead,  mem)
  2103.         TUINT                 TMEMHEAD* TAPTR
  2104.  
  2105.     FUNCTION
  2106.         this function returns the size of an allocation made
  2107.         with TStaticAlloc() or TStaticRealloc().
  2108.  
  2109.     INPUTS
  2110.         memhead - pointer to an initialized memheader structure
  2111.         mem     - previously allocated block of memory, or TNULL
  2112.  
  2113.     RESULTS
  2114.         size    - size of the allocation [bytes].
  2115.  
  2116.     NOTE
  2117.         it is not allowed to pass TNULL or zero for either memhead
  2118.         or mem. this function is designed for low overhead.
  2119.    
  2120.     SEE ALSO
  2121.         TInitMemHeadA(), TStaticAlloc(), TStaticRealloc()
  2122.  
  2123.  
  2124. teklib/TCreatePool
  2125.  
  2126.     NAME
  2127.         TCreatePool - create pooled allocator.
  2128.  
  2129.     SYNOPSIS
  2130.         pool = TCreatePool(mmu,  chunksize, thressize, tags)
  2131.         TAPTR              TAPTR TUINT      TUINT      TTAGITEM*
  2132.  
  2133.     FUNCTION    
  2134.         create and initialize a pooled memory allocator.
  2135.  
  2136.         pools can automatically expand and shrink on demand. many
  2137.         individual allocations may fit into chunks which are being
  2138.         maintained internally by the pooled allocator.
  2139.         
  2140.         there is no need to free individual allocations requested
  2141.         from a pooled allocator; they will be freed automatically
  2142.         when the pool is destroyed with TDestroy().
  2143.  
  2144.         chunksize is the size of new chunks to be allocated from
  2145.         a parent memory manager, when a new allocation cannot be
  2146.         satisfied from the current set of chunks.
  2147.         
  2148.         thressize is the maximum size of allocations that will be
  2149.         allocated from regular chunks. allocations larger than
  2150.         thressize will request new chunks of their own.
  2151.         
  2152.         pools created with 'dynamic growth' will automatically adapt
  2153.         their chunksize, and always allocate new chunks larger than
  2154.         required by a single allocation. TPoolRealloc() will utilize
  2155.         this prefetch memory to allow rapidly growing reallocations
  2156.         with very few overhead. with dynamic growth enabled, chunksize
  2157.         divided by thressize will be used as the pool's prefetch ratio.
  2158.  
  2159.     INPUTS
  2160.         mmu       - parent memory manager
  2161.         chunksize - size of chunks to be allocated from parent
  2162.                     memory manager
  2163.         thressize - maximum size of allocations that will be
  2164.                     requested from chunks of their own
  2165.         taglist   - pointer to an array of tag items
  2166.         
  2167.     TAGS
  2168.         TMem_DynGrow, TBOOL
  2169.             when this argument is set to TTRUE, chunksize/threshold
  2170.             are interpreted as an initial ratio for dynamic pool
  2171.             growth. default: TTRUE
  2172.         
  2173.     RESULTS
  2174.         pool - an initialized memory pool, or TNULL if something
  2175.                went wrong.
  2176.  
  2177.     SEE ALSO
  2178.         TPoolAlloc(), TPoolRealloc(), TPoolFree(), TPoolGetSize(),
  2179.         TDestroy()
  2180.  
  2181.  
  2182. teklib/TPoolAlloc
  2183.  
  2184.     NAME
  2185.         TPoolAlloc - allocate memory from a pool.
  2186.  
  2187.     SYNOPSIS
  2188.         mem = TPoolAlloc(pool, size)
  2189.         TAPTR            TAPTR TUINT
  2190.  
  2191.     FUNCTION
  2192.         allocate a block of memory of the given size from a pool.
  2193.  
  2194.    INPUTS
  2195.         pool - an object created with TCreatePool()
  2196.         size - size of the allocation [bytes]
  2197.  
  2198.     RESULTS
  2199.         mem - pointer to a block of memory, or TNULL when the request
  2200.               could not be satisfied.
  2201.     
  2202.     SEE ALSO
  2203.         TCreatePool(), TPoolFree(), TPoolRealloc(), TPoolGetSize()
  2204.  
  2205.  
  2206. teklib/TPoolFree
  2207.  
  2208.     NAME
  2209.         TPoolFree - return memory to a pool.
  2210.  
  2211.     SYNOPSIS
  2212.         TPoolFree(pool, mem)
  2213.         void      TAPTR TAPTR
  2214.  
  2215.     FUNCTION
  2216.         return a block of memory to a pool.
  2217.  
  2218.     INPUTS
  2219.         pool - a pooled allocator created with TCreatePool().
  2220.         mem  - pointer to a block of memory allocated with
  2221.                TPoolAllloc().
  2222.  
  2223.     SEE ALSO
  2224.         TCreatePool(), TPoolAlloc(), TPoolRealloc(), TPoolGetSize()
  2225.  
  2226.  
  2227. teklib/TPoolRealloc
  2228.  
  2229.     NAME
  2230.         TPoolRealloc - resize a block of memory in a pool.
  2231.  
  2232.     SYNOPSIS
  2233.         mem = TPoolRealloc(pool, oldmem, size)
  2234.         TAPTR              TAPTR TAPTR   TUINT
  2235.  
  2236.     FUNCTION
  2237.         resizes a memory block that was allocated from a pool to the
  2238.         specified size, and returns a valid pointer to the resized block
  2239.         of memory, or TNULL when the memory block could not be resized. 
  2240.        
  2241.         when a memory block is passed, but the specified size is zero,
  2242.         the memory block will be returned to the pool, and the result of
  2243.         this function is TNULL.
  2244.         
  2245.         when a size is specified, and the memory block is TNULL, this
  2246.         function will try to allocate a new block of the given size.
  2247.         
  2248.         if mem is TNULL and size is zero, this function will return
  2249.         TNULL.
  2250.  
  2251.     INPUTS
  2252.         pool    - an object created with TCreatePool().
  2253.         oldmem  - pointer to a block of memory to be resized.
  2254.         size    - new size of the memory block.
  2255.  
  2256.     RESULTS        
  2257.         mem     - resized (or freshly allocated) block of memory,
  2258.                   or TNULL.
  2259.  
  2260.     NOTES
  2261.         reallocation may require that the given block of memory
  2262.         needs to be moved in memory, i.e. pointers to this area
  2263.         may become invalid.
  2264.     
  2265.     SEE ALSO
  2266.         TPoolAlloc(), TPoolFree(), TCreatePool(), TPoolGetSize()
  2267.  
  2268.  
  2269. teklib/TPoolGetSize
  2270.  
  2271.     NAME
  2272.         TPoolGetSize - get size of an allocation from a pool.
  2273.  
  2274.     SYNOPSIS
  2275.         size = TPoolGetSize(TAPTR pool, mem)
  2276.         TUINT               TAPTR       TAPTR
  2277.  
  2278.     FUNCTION
  2279.         this function returns the size of an allocation made
  2280.         with TPoolAlloc() or TPoolRealloc(). if mem is TNULL,
  2281.         this function returns 0.
  2282.  
  2283.     INPUTS
  2284.         mem  - previously allocated block of memory, or TNULL.
  2285.  
  2286.     RESULTS
  2287.         size - size of the allocation [bytes].
  2288.  
  2289.     SEE ALSO
  2290.         TPoolAlloc(), TPoolRealloc()
  2291.  
  2292.  
  2293. teklib/TInitMMU
  2294.  
  2295.     NAME
  2296.         TInitMMU - initialize a memory management unit.
  2297.  
  2298.     SYNOPSIS
  2299.         success = TInitMMU(mmu,  allocator, mmutype, tags)
  2300.         TBOOL              TMMU* TAPTR      TUINT    TTAGITEM*
  2301.  
  2302.     FUNCTION 
  2303.         initialize a TMMU structure and prepare it for being
  2304.         used as a memory management unit.
  2305.  
  2306.     INPUTS
  2307.         mmu       - pointer to a TMMU structure
  2308.         allocator - allocator underlying the MMU to be created
  2309.         mmutype   - type of MMU to be created.
  2310.             TMMUT_Kernel
  2311.                 setup a kernel MMU. allocator must be TNULL. the
  2312.                 newly created MMU will allocate from the kernel.
  2313.  
  2314.             TMMUT_Static
  2315.                 setup a static memory MMU. allocator must point
  2316.                 to a memheader initialized with TInitMemHead().
  2317.             
  2318.             TMMUT_Pooled
  2319.                 setup a pooled MMU. allocator must point to a
  2320.                 pooled allocator created with TCreatePool().
  2321.             
  2322.             TMMUT_MMU
  2323.                 setup a MMU on top of another MMU, implementing
  2324.                 no additional functionality. allocator must point
  2325.                 to another MMU.
  2326.             
  2327.             TMMUT_Tracking
  2328.                 setup a tracking MMU on top of another MMU. allocator
  2329.                 must point to another MMU, or TNULL (which is equivalent
  2330.                 to a kernel allocator). the resulting MMU will return all
  2331.                 pending allocations to its parent MMU when it is
  2332.                 destroyed.
  2333.             
  2334.             TMMUT_TaskSafe
  2335.                 setup a MMU on top of another MMU, implementing safe
  2336.                 multitasking accesses across tasks, i.e. multiple tasks
  2337.                 are allowed to operate on the resulting MMU in parallel.
  2338.                 allocator must point to another MMU, or TNULL (which is
  2339.                 equivalent to a kernel MMU).
  2340.             
  2341.             TMMUT_Message
  2342.                 setup a special MMU for being used as a message
  2343.                 allocator. allocator must point to another message MMU,
  2344.                 or TNULL. aside from special precautions for allocating
  2345.                 messages, message MMUs also implement multitasking
  2346.                 safety and tracking capabilities.
  2347.  
  2348.             some MMU types may be combined, currently it is possible to
  2349.             initialize a MMU implementing TMMUT_TaskSafe|TMMUT_Tracking
  2350.             and TMMUT_TaskSafe|TMMUT_Pooled.
  2351.  
  2352.         tags      - pointer to an array of tag items
  2353.  
  2354.     TAGS
  2355.         none defined yet
  2356.     
  2357.     RESULTS        
  2358.         success  - boolean. TFALSE if an invalid combination of a MMU's
  2359.                    capabilities was specified.
  2360.  
  2361.     NOTES
  2362.         a MMU is destroyed with a call to TDestroy().
  2363.  
  2364.     SEE ALSO
  2365.         TDestroy(), TMMUAlloc(), TMMUAlloc0(), TMMURealloc(), TMMUFree(),
  2366.         TMMUGetSize()
  2367.  
  2368.  
  2369. teklib/TMMUAlloc
  2370.  
  2371.     NAME
  2372.         TMMUAlloc - allocate memory via MMU.
  2373.  
  2374.     SYNOPSIS
  2375.         mem = TMMUAlloc(mmu,  size)
  2376.         TAPtR           TAPTR TUINT
  2377.  
  2378.     FUNCTION
  2379.         allocate a block of memory via a MMU. returns TNULL when
  2380.         the request could not be satisfied. 
  2381.         
  2382.     INPUTS
  2383.         mmu  - pointer to a memory management unit.
  2384.         size - size of the allocation [bytes].
  2385.  
  2386.     RESULTS
  2387.         mem  - pointer to a block of memory, or TNULL.
  2388.  
  2389.     SEE ALSO
  2390.         TMMUFree(), TMMUAlloc0(), TMMURealloc(), TMMUGetSize(),
  2391.         TInitMMU()
  2392.  
  2393.  
  2394. teklib/TMMUAlloc0
  2395.  
  2396.     NAME
  2397.         TMMUAlloc0 - allocate blank memory via MMU.
  2398.  
  2399.     SYNOPSIS
  2400.         mem = TMMUAlloc0(mmu,  size)
  2401.         TAPTR            TAPTR TUINT
  2402.  
  2403.     FUNCTION
  2404.         allocate a blank block of memory via a MMU, i.e. a block
  2405.         of memory that is filled with zero-bytes. returns TNULL
  2406.         when the request could not be satisfied. 
  2407.         
  2408.     INPUTS
  2409.         mmu  - pointer to a memory management unit.
  2410.         size - size of the allocation [bytes].
  2411.  
  2412.     RESULTS
  2413.         mem  - pointer to a block of memory, or TNULL.
  2414.  
  2415.     SEE ALSO
  2416.         TMMUAlloc0(), TMMUFree(), TMMURealloc(), TMMUGetSize(),
  2417.         TInitMMU()
  2418.  
  2419.  
  2420. teklib/TMMUFree
  2421.  
  2422.     NAME
  2423.         TMMUFree - free memory via MMU.
  2424.  
  2425.     SYNOPSIS
  2426.         TMMUFree(mmu,  mem)
  2427.                  TAPTR TAPTR
  2428.  
  2429.     FUNCTION
  2430.         free a block of memory via MMU.
  2431.  
  2432.     INPUTS
  2433.         mmu  - pointer to a memory management unit.
  2434.         mem  - block of memory to be freed.
  2435.         
  2436.     SEE ALSO
  2437.         TMMUAlloc(), TMMUAlloc0(), TMMURealloc(), TMMUGetSize(),
  2438.         TInitMMU()
  2439.  
  2440.  
  2441. teklib/TMMURealloc
  2442.  
  2443.     NAME
  2444.         TMMURealloc - resize a block of memory via MMU.
  2445.  
  2446.     SYNOPSIS
  2447.         newmem = TMMURealloc(mmu,  oldmem, size)
  2448.         TAPTR                TAPTR TAPTR   TUINT32
  2449.  
  2450.     FUNCTION
  2451.         resizes a memory block that was previously allocated from a MMU
  2452.         to the specified size, and returns a valid pointer to the resized
  2453.         block of memory, or TNULL when the memory block could not be
  2454.         resized. 
  2455.        
  2456.         when a memory block is passed, and the specified size is zero,
  2457.         the memory block will be returned to the pool, and the result of
  2458.         this function is TNULL.
  2459.         
  2460.         when a size is specified, and the memory block is TNULL, this
  2461.         function will try to allocate a new block of the given size.
  2462.         
  2463.         if mem is TNULL and size is zero, this function will return
  2464.         TNULL.
  2465.  
  2466.     INPUTS
  2467.         mmu     - pointer to a memory management unit.
  2468.         oldmem  - block of memory to be resized.
  2469.         size    - new size of the memory block.
  2470.         
  2471.     NOTES
  2472.         reallocation may require that the given block of memory
  2473.         needs to be moved in memory, i.e. pointers to this area
  2474.         may become invalid.
  2475.  
  2476.     RESULTS
  2477.         mem  - pointer to a resized (or freshly allocated) block of
  2478.                memory, or TNULL.
  2479.         
  2480.     SEE ALSO
  2481.         TMMUAlloc(), TMMUAlloc0(), TMMUFree(), TMMUGetSize(),
  2482.         TInitMMU()
  2483.  
  2484.  
  2485. teklib/TMMUGetSize
  2486.  
  2487.     NAME
  2488.         TMMUGetSize - get size of an allocation from a MMU.
  2489.  
  2490.     SYNOPSIS
  2491.         size = TMMUGetSize(mmu,  mem)
  2492.         TUINT              TAPTR TAPTR
  2493.  
  2494.     FUNCTION
  2495.         this function returns the size of an allocation made
  2496.         with TMMUAlloc(), TMMUAlloc0(), or TMMURealloc().
  2497.  
  2498.     INPUTS
  2499.         mem  - previously allocated block of memory, or TNULL.
  2500.  
  2501.     RESULTS
  2502.         size - size of the allocation [bytes].
  2503.  
  2504.     SEE ALSO
  2505.         TMMUAlloc(), TMMUAlloc0(), TMMURealloc(), TMMUFree(),
  2506.         TInitMMU()
  2507.  
  2508.  
  2509. teklib/TMMUAllocHandle
  2510.  
  2511.     NAME
  2512.         TMMUAllocHandle - allocate a handle.
  2513.  
  2514.     SYNOPSIS
  2515.         mem = TMMUAllocHandle(mmu,  destructor,  size)
  2516.         TUINT                 TAPTR TDESTROYFUNC TUINT
  2517.  
  2518.     FUNCTION
  2519.         allocate a generic handle with destructor. this function
  2520.         expects and initializes a heading THNDL structure in the
  2521.         allocated block of memory.
  2522.  
  2523.         a handle allocated with this function can be destroyed
  2524.         with TDestroy(), which will call the supplied destructor
  2525.         before the allocated memory is returned to its MMU.
  2526.  
  2527.     INPUTS
  2528.         mmu        - memory manager
  2529.         destructor - destructor function being invoked with
  2530.                      TDestroy(), or TNULL
  2531.         size       - total size of the allocation, including
  2532.                      the heading THNDL structure
  2533.  
  2534.     RESULTS
  2535.         mem        - handle, or TNULL
  2536.  
  2537.     SEE ALSO
  2538.         TDestroy(), TMMUAllocHandle0(), TMMUFreeHandle(), TInitMMU()
  2539.  
  2540.  
  2541. teklib/TMMUAllocHandle0
  2542.  
  2543.     NAME
  2544.         TMMUAllocHandle0 - allocate a handle with blank memory.
  2545.  
  2546.     SYNOPSIS
  2547.         mem = TMMUAllocHandle0(mmu,  destructor,  size)
  2548.         TUINT                  TAPTR TDESTROYFUNC TUINT
  2549.  
  2550.     FUNCTION
  2551.         allocate a generic handle with destructor. this function
  2552.         expects and initializes a heading THNDL structure in the
  2553.         allocated block of memory.
  2554.  
  2555.         a handle allocated with this function can be destroyed
  2556.         with TDestroy(), which will call the supplied destructor
  2557.         before the allocated memory is returned to its MMU.
  2558.         
  2559.         unlike TMMUAllocHandle(), this function will zero out
  2560.         the memory followed by the heading THNDL structure.
  2561.  
  2562.     INPUTS
  2563.         mmu        - memory manager
  2564.         destructor - destructor function being invoked with
  2565.                      TDestroy(), or TNULL
  2566.         size       - total size of the allocation, including
  2567.                      the heading THNDL structure
  2568.  
  2569.     RESULTS
  2570.         mem        - handle, or TNULL
  2571.  
  2572.     SEE ALSO
  2573.         TDestroy(), TMMUAllocHandle(), TMMUFreeHandle(), TInitMMU()
  2574.  
  2575.  
  2576. teklib/TMMUFreeHandle
  2577.  
  2578.     NAME
  2579.         TMMUFreeHandle - free a handle
  2580.  
  2581.     SYNOPSIS
  2582.         TMMUFreeHandle(handle)
  2583.                        TAPTR
  2584.  
  2585.     FUNCTION
  2586.         free a handle and return its memory to the MMU it was
  2587.         allocated from. unlike TDestroy(), this function will not
  2588.         call a handle's destructor.
  2589.  
  2590.     INPUTS
  2591.         handle     - handle allocated with TMMUAllocHandle() or
  2592.                      TMMUAllocHandle0()
  2593.  
  2594.     SEE ALSO
  2595.         TMMUAllocHandle(), TDestroy(), TInitMMU()
  2596.  
  2597.  
  2598. teklib/TDestroy
  2599.  
  2600.     NAME
  2601.         TDestroy - destroy a generic handle
  2602.  
  2603.     SYNOPSIS
  2604.         result = TDestroy(handle)
  2605.         TINT              TAPTR
  2606.  
  2607.     FUNCTION
  2608.         call a handle's destroy function.
  2609.         
  2610.         the destroy function's object-specific return value will
  2611.         be returned to the caller.
  2612.         
  2613.         if handle is TNULL, this function returns 0.
  2614.  
  2615.     INPUTS
  2616.         handle   - generic handle such as allocated with
  2617.                    TMMUAllocHandle() or TMMUAllocHandle0().
  2618.                    it is safe to pass TNULL here.
  2619.  
  2620.     RESULTS
  2621.         result   - return value, as returned by the handle's
  2622.                    destroy function. 0 if handle is TNULL or
  2623.                    when a handle's destroy function is TNULL.
  2624.  
  2625.     SEE ALSO
  2626.         TMMUAllocHandle(), TMMUFreeHandle(), TInitMMU()
  2627.  
  2628.  
  2629. teklib/TAddSockPort
  2630.  
  2631.     NAME
  2632.         TAddSockPort - make msgport available in internet namespace
  2633.  
  2634.     SYNOPSIS
  2635.         portnr = TAddSockPort(msgport, portnr, tags)
  2636.         TUINT                 TPORT*   TUINT   TTAGITEM*
  2637.  
  2638.     FUNCTION
  2639.         add a messageport to the internet namespace and make it
  2640.         available on the given internet port number. if portnr is
  2641.         zero, this function will try to allocate a new port number
  2642.         and bind the messageport to it. in either case, the internet
  2643.         port number will be returned to the caller. a return value
  2644.         of zero indicates failure.
  2645.  
  2646.     INPUTS
  2647.         msgport - messageport to be added to the internet namespace
  2648.         portnr  - dedicated internet port number to add the messageport
  2649.                   to, or zero for no preference
  2650.         tags    - pointer to a list of tag items
  2651.  
  2652.     TAGS
  2653.         TSock_IdleTimeout, TTIME *
  2654.             pointer to a time structure holding a timeout for idle
  2655.             internet connections to this messageport. when this timeout
  2656.             expires, the respective connection will be dropped without
  2657.             further notice, and further communication with that peer
  2658.             will be rejected unless the peer reconnects to this
  2659.             messageport.
  2660.             default: 128 seconds
  2661.         
  2662.         TSock_MaxMsgSize, TUINT
  2663.             maximum size allowed for a single message incoming via
  2664.             network, in bytes. a peer sending larger messages will be
  2665.             silently dropped without further notice, and further
  2666.             communication with that peer will be rejected unless it
  2667.             reconnects to this messageport.
  2668.             default: -1 (no limit)
  2669.  
  2670.     RESULTS
  2671.         portnr  - actual internet port number to which the messageport
  2672.                   was added, or zero for failure.
  2673.  
  2674.     SEE ALSO
  2675.         TFindSockPort(), TRemSockPort(), TCreatePort()
  2676.  
  2677.  
  2678. teklib/TFindSockPort
  2679.  
  2680.     NAME
  2681.         TFindockPort - find a remote message port.
  2682.  
  2683.     SYNOPSIS
  2684.         msgport = TFindSockPort(task, ipname, portnr, tags)
  2685.         TPORT*                  TAPTR TSTRPTR TUINT16 TTAGITEM*
  2686.  
  2687.     FUNCTION
  2688.         find a remote messageport that has been announced to
  2689.         the internet namespace with TAddSockPort(). a proxy
  2690.         to the remote messageport will be returned.
  2691.  
  2692.     INPUTS
  2693.         task    - task, referring to the caller's current context
  2694.         ipname  - ip name string
  2695.         portnr  - internet port number
  2696.         tags    - pointer to a list of tag items
  2697.     
  2698.     TAGS
  2699.         TSock_ReplyTimeout, TTIME *
  2700.             pointer to a time structure holding a timeout for
  2701.             replies pending over remote connections. when the
  2702.             timeout expires, the message port will fall into a
  2703.             'broken' state, and reject further communication with
  2704.             the remote peer.
  2705.             default: 32 seconds
  2706.  
  2707.     RESULTS
  2708.         msgport - proxy to the remote msgport, or TNULL on failure.
  2709.             
  2710.     SEE ALSO
  2711.         TFindSockPort(), TRemSockPort(), TCreatePort()
  2712.  
  2713.  
  2714. teklib/TRemSockPort
  2715.  
  2716.     NAME
  2717.         TRemSockPort - remove a message port from publicity.
  2718.  
  2719.     SYNOPSIS
  2720.         TRemSockPort(msgport)
  2721.                      TPORT*
  2722.  
  2723.     FUNCTION
  2724.         remove a messageport from the internet namespace.
  2725.  
  2726.     INPUTS
  2727.         msgport - msgport that has previously been added to the
  2728.                   internet namespace with TAddSockPort().
  2729.             
  2730.     SEE ALSO
  2731.         TFindSockPort(), TAddSockPort(), TCreatePort()
  2732.  
  2733.  
  2734.